7.2. Краткое описание Repository API¶
7.2.1. Назначение и общий функционал работы с API¶
Концепция репозиториев для абстрагирования вызовов API создана в рамках работы над задачей #10448
Репозитории инжектированы в глобальный объект и могут вызываться либо через this, либо через app (в asyncData).
Все методы репозиториев возвращают Promise. Далее, для удобства, в качестве возвращаемых типов методов используются типы, возвращаемые при разрешении Promise.
Внутри репозитория доступны общие объекты приложения: $backend, $store, $i18n.
Примечание
При использовании данного API во внешних скриптах в примерах this необходимо заменить на repo и название репозитория использовать без знака $
Пример:
let data = await $repos.schemaRepository('coordinates').list({
clauses: sites.map(site=>{
return {
field:'siteid',
operand:'eq',
value:site['site_id'],
operator:"or",
}
}),
"fields": ["country","latitude","longitude","siteid",'street'],
"offset": 0
}
)
7.2.2. schemaRepository¶
Используется для работы с данными и метаданными схем.
Вызов: this.$schemaRepository(schema), где schema может быть либо именем схемы, либо ID, в зависимости от эндпоинта.
7.2.2.1. Методы работы со схемой¶
- get(id, fields) - возвращает одну запись из схемы. Параметры: id - идентификатор получаемой записи; fields - массив имён полей, которые должны быть включены в запись.
- create(data, params) - создаёт запись в схеме. Параметры: data - key-value объект с данными для создания; params - query-параметры для включения в URL.
- list(params) - выбрать данные из схемы (все, либо в соответствии с переданными параметрами). Параметр: params - параметры запроса. Возвращает Array.
- listUnique(params) - выбрать уникальные записи из схемы (т.е. сгруппированные по запрашиваемым полям). Параметр: params - параметры запроса, где свойство distinct всегда будет иметь значение true.
- listPage(pageSize, page, params) - выбрать страницу данных из схемы. Параметры: pageSize - количество записей на странице (по умолчанию - 0); page - номер выбираемой страницы (по умолчанию - 0); params - параметры запроса. Возвращает Object со следующими свойствами: data - массив с выбранными записями; total - общее количество записей в схеме данных.
- update(data, params) - обновить запись в схеме. Параметры: data - key-value объект с данными для обновления; params - query-параметры для включения в URL.
- delete(id) - удалить запись из схемы. Параметр: id - идентификатор удаляемой записи
- getMetadata() - получить мета-информацию о схеме. При вызове метода проверяется существование схемы в локальном хранилище (store.state.app.schemas), и если есть, то возвращается локальный объект. Если нет - то запрашивается с бэкенда и сохраняется в локальном хранилище.
- listMetadata() - получить список мета-информации о всех схемах (вызов репозитория может осуществляться без указания схемы)
- clauses.get() - возвращает шаблоны фильтров для схемы
7.2.2.2. Методы работы с вложениями¶
- attachment(field, id).get(mimeType) - возвращает вложение для поля field схемы и идентификатора записи id. Параметр mimeType - опциональный, по умолчанию - „application/octet-stream“.
- attachment(field, id).upload(data, params) - загружает вложение для поля field схемы и идентификатора записи id. Парамерты: data - данные для загрузки; params - не обязательные дополнительные параметры для передачи в метод запроса.
- attachment(field, id).delete() - удаляет вложение для поля field схемы и идентификатора записи id.
7.2.2.3. Параметры вызова методов типа list(params) и listPage(params)¶
При вызове методов API могут передаваться параметры. Параметры - объект, который может содержать не обязательные свойства:
- fieldName {String} - поле в котором будет находится строгое соответствие значения, указанного в параметре value. Если value не указан, то и этот параметр игнорируется.
- value {String, Array} - значение, строгое соответствие которого будет находится по полю fieldName. Если значение - строка, то сравнение значения поля происходит по эквивалентности строки. Если значение - массив строк, то сравнение значения поля происходит по эквивалентности любой из строк массива. Если fieldName не указан, то и этот параметр игнорируется.
- clauses {Array} - дополнительные условия выборки в формате clauses вызовов API. Для подробностей можно обратиться к документации Clause API (см Раздел 7.5).
- fields {Array} - список полей, которые нужно вернуть в выборке данных.
- maxRows {Number} - максимальное количество записей в выборке.
- offset {Number} - смещение относительно первой записи при выборке данных.
- distinct {Boolean} - Флаг, возвращать ли только уникальные записи. true - для уникальных записей. По умолчанию - false.
7.2.2.4. Примеры вызовов¶
this.$schemaRepository(„incidents“).list() - выбрать все данные из схемы incidents
this.$schemaRepository(„people“).list({fields: [„full_name“]}) - выбрать все данные из схемы people, при этом вернуть только поле full_name.
this.$schemaRepository(„incidents“).listPage(10, 3) - выбрать 10 записей 3-й страницы из схемы incidents
this.$schemaRepository(„schm001“).getMetadata() - получить мета-информацию о схеме с id == „schm001“
this.$schemaRepository().listMetadata() - получить список мета-информации о всех схемах
this.$schemaRepository(„schm001“).clauses.get() - получить шаблоны фильтров для схемы с id == „schm001“
7.2.3. uiRepository¶
Используется для работы с объектами UI.
7.2.3.1. Методы работы с UI¶
- console(id) - возвращает мета-информацию о консоли по идентификатору. Параметры: id - идентификатор консоли.
- form(id) - возвращает мета-информацию о форме по идентификатору. Параметры: id - идентификатор формы. При вызове метода проверяется существование формы в локальном хранилище (store.state.app.forms), и если есть, то возвращается локальный объект. Если нет - то запрашивается с бэкенда и сохраняется в локальном хранилище.
- consoles(schemaId) - возвращает список консолей для схемы. Параметры: schemaId - идентификатор схемы.
- forms(schemaId) - возвращает список форм для схемы. Параметры: schemaId - идентификатор схемы.
- sidebars() - возвращает список всех сайдбаров.
- sidebar(id) - возвращает конкретный сайдбар. Параметры: id - идентификатор сайдбара.
- svg() - возвращает список всех svg.
- dashboard.panes() - возвращает список всех доступных инструментальных панелей
- dashboard.pane(id) - возвращает конкретную инструментальную панель. Параметры: id - идентификатор панели.
- dashboard.chart(id) - возвращает конкретную диаграмму из инструментальной панели. Параметры: id - идентификатор диаграммы.
7.2.3.2. Примеры вызовов¶
this.$uiRepository.console(„inc_con_001“) - получить мета-информацию о консоли с id == „inc_con_001“.
7.2.4. adminRepository¶
Содержит методы доступа к эндпоинтам администрирования.
7.2.4.1. Методы администсрирования бэкенда¶
Здесь работает фабрика методов, поэтому, как правило, необходимый метод можно вычислить исходя из требуемого пути API. Например, для /admin/forms/get метод будет: $this.$adminRepository.forms.get(). Если путь содержит подчёркивание, то метод необходимо вызывать без подчёркивания в «camelСase» (см. примеры). В каждый метод можно передать параметр data.
Кроме фабрики стандартных методов репозиторий содержит методы, которые отличаются от стандартных, либо созданы дополнительно для удобства работы с бэкендом. Такие методы приведены ниже.
7.2.4.2. Методы управления локализацией¶
- i18n.listNames() - запрос на получение списка существующих локалей в i18n.
7.2.4.3. Методы управления каталогом услуг¶
- catalog.listGroupItems(groupId) - запрос списка услуг для конкретной группы каталога услуг. groupId - ID группы, для которой необходимо запросить список услуг.
7.2.4.4. Методы управления резервным копированием/восстановлением¶
- backup() - возвращает данные для резервного копирования
- restore(data) - восстанавливает данные. Параметры data - данные для восстановления.
7.2.4.5. Методы управления свойствами¶
- properties.get() - возвращает все свойства
- properties.get(property) - возвращает конкретное свойство property
- properties.save(properties) - сохраняет свойства, переданные в объекте properties
- properties.add(property, {value, isGlobal, description}) - добавляет новое свойство property со значением value, признаком глобального свойства isGlobal (по умолчанию - false) и описанием description.
- properties.update(property, {value, isGlobal, description}) - обновляет свойство property значением value, признаком глобального свойства isGlobal (по умолчанию - false) и описанием description.
- properties.delete(propety) - удаляет свойство property
7.2.4.6. Примеры вызовов¶
this.$adminRepository.sidebars.list() - получить список всех сайдбаров (в режиме администратора)
this.$adminRepository.sidebars.get({id: „sb_6“}) - получить мета-информацию о сайдбаре с id == „sb_06“ (в режиме администратора)
this.$adminRepository.catalog.listItems() - Получить список элементов каталога (в режиме администратора)
this.$adminRepository.properties.add(„test_prop“, {value: „test_value“}) - Добавить новое свойство test_prop со значением test_value, без описания и признаком глобального свойства false.
7.2.5. appRepository¶
Содержит методы для работы с общими объектами приложения
7.2.5.1. Методы для работы с объектами приложения¶
- auth.token(auth) - возвращает токен при успешной аутентификации. Параметр auth - объект с именем пользователя и паролем для аутентификации.
- i18n() - возвращает объект с локализованными свойствами.
- enums() - возвращает все enums.
7.2.5.2. Примеры вызовов¶
this.$appRepository.auth.token({ user: „user“, password: „der_parol“ })
this.$appRepository.i18n()
7.2.6. userRepository¶
Содержит методы для работы с настройками пользователя. При определении пользователя берётся текущий пользователь из контекста.
7.2.6.1. Методы для работы с настройками пользователя¶
- preferences.get() - Получить настройки пользователя.
- preferences.add(prefs) - Создать настройки пользователя. Параметр prefs - объект с настройками пользователя для создания.
- preferences.update(prefs) - Обновить настройки пользователя. Параметр prefs - объект с настройками пользователя для обновления.
- preferences.delete() - Удалить настройки пользователя.